Zvládnutí ověřování formulářů pomocí React `experimental_useFormStatus`

Když se načte JavaScript, React unese proces odeslání formuláře, zabrání načtení celé stránky a asynchronně provede serverovou akci. To nám dává to nejlepší z obou světů: odolnost serverově renderovaných aplikací a bohatou, interaktivní zkušenost single-page aplikace (SPA).

Tento model přesouvá zdroj pravdy pro obchodní logiku a ověřování zpět na server (nebo do serverového prostředí). Kód na straně klienta se stává jednodušším, primárně se zabývá renderováním UI na základě *stavu* této serverové komunikace. Právě zde přichází do hry `useFormStatus`.

Pod pokličkou: Co je `experimental_useFormStatus`?

Hook `experimental_useFormStatus` je nástroj na straně klienta navržený k poskytování informací o posledním odeslání nadřazeného elementu ``. Je to hook pouze pro čtení, který komponentě sděluje vše, co potřebuje vědět o stavu odeslání formuláře, aniž by bylo nutné předávat jakékoli vlastnosti.

Základní funkčnost

Představte si odesílací tlačítko uvnitř velkého formuláře. Jak toto tlačítko ví, kdy se formulář odesílá? Tradičně byste museli předat stavovou proměnnou, jako je `isSubmitting`, přes několik vrstev komponent (prop drilling). S `useFormStatus` může komponenta tlačítka zjistit tyto informace sama.

Hook musí být volán z komponenty, která je renderována uvnitř elementu ``. Poté poskytuje informace o stavu konkrétního životního cyklu formuláře.

Anatomie hooku `useFormStatus`

Když zavoláte `const status = useFormStatus()`, získáte zpět objekt s následujícími klíčovými vlastnostmi:

• `pending` (boolean): Toto je nejčastěji používaná vlastnost. Je `true`, pokud je nadřazený formulář aktuálně odesílán, a `false` jinak. Je ideální pro zakázání tlačítek, zobrazení indikátorů načítání nebo stylování čekajících stavů.
• `data` (FormData): Objekt implementující rozhraní `FormData`. Obsahuje data, která byla odeslána s formulářem. To je neuvěřitelně užitečné pro implementaci optimistických aktualizací UI – například zobrazení komentáře uživatele v seznamu ihned po jeho odeslání, ještě předtím, než server potvrdí jeho vytvoření.
• `method` (string): HTTP metoda ('get' nebo 'post') použitá pro odeslání formuláře.
• `action` (function): Odkaz na funkci serverové akce, která byla vyvolána během odeslání.

Zlaté pravidlo: Potomek `<form>`

Kritické pravidlo, které si musíte zapamatovat, je, že komponenta používající `useFormStatus` musí být renderována jako potomek elementu `<form>`, který sleduje. Nemůže být ve stejné komponentě, která renderuje samotný tag `<form>`, protože potřebuje mít přístup ke kontextu formuláře. Proto téměř vždy uvidíte komponenty, jako je `<SubmitButton />`, vytvořené samostatně pro umístění logiky `useFormStatus`.

Jednoduchý příklad: Chytré odesílací tlačítko

Podívejme se na nejběžnější případ použití v akci. Místo standardního `<button>` vytvoříme komponentu, která si je vědoma stavu odeslání formuláře.

Soubor: SubmitButton.js

import { experimental_useFormStatus as useFormStatus } from 'react-dom'; export function SubmitButton() { const { pending } = useFormStatus(); return ( <button type="submit" disabled={pending}> {pending ? 'Odesílám...' : 'Zaregistrovat se'} </button> ); }

Soubor: SignUpForm.js

import { SubmitButton } from './SubmitButton'; import { signUpAction } from './actions'; // Serverová akce export function SignUpForm() { return ( <form action={signUpAction}> <label htmlFor="email">Email:</label> <input type="email" id="email" name="email" required /> <br /> <SubmitButton /> </form> ); }

V tomto příkladu je `SubmitButton` zcela soběstačný. Nepřijímá žádné vlastnosti. Používá `useFormStatus` ke zjištění, kdy je `SignUpForm` ve stavu pending, a automaticky se zakáže a změní svůj text. To je výkonný vzor pro oddělení a vytváření opakovaně použitelných komponent, které si jsou vědomy formuláře.

Jádro věci: Logika ověřování založená na stavu

Nyní přicházíme k základnímu konceptu. `useFormStatus` není jen pro stavy načítání; je klíčovým faktorem pro jiný způsob myšlení o ověřování.

Definování „ověřování stavu“

Ověřování založené na stavu je vzor, kdy je zpětná vazba ověřování primárně doručována uživateli v reakci na pokus o odeslání formuláře. Namísto ověřování při každém stisku klávesy (`onChange`) nebo když uživatel opustí pole (`onBlur`), se primární logika ověřování spouští, když uživatel odešle formulář. Výsledek tohoto odeslání – jeho *stav* (např. úspěch, chyba ověření, chyba serveru) – se poté použije k aktualizaci UI.

Tento přístup se dokonale shoduje s React Server Actions. Serverová akce se stává jediným zdrojem pravdy pro ověřování. Přijímá data formuláře, ověřuje je podle vašich obchodních pravidel (např. „je tento e-mail již používán?“) a vrací strukturovaný objekt stavu, který indikuje výsledek.

Role partnera: `experimental_useFormState`

`useFormStatus` nám říká, *co* se děje (pending), ale neříká nám *výsledek* toho, co se stalo. K tomu potřebujeme jeho sesterský hook: `experimental_useFormState`.

`useFormState` je hook navržený k aktualizaci stavu na základě výsledku akce formuláře. Jako argumenty bere funkci akce a počáteční stav a vrací nový stav a zabalenou funkci akce, kterou předáte do formuláře.

const [state, formAction] = useFormState(myAction, initialState);

• `state`: Bude obsahovat návratovou hodnotu z posledního spuštění `myAction`. Zde získáme naše chybové zprávy.
• `formAction`: Toto je nová verze vaší akce, kterou byste měli předat vlastnosti `action` elementu `<form>`. Když je tato funkce volána, spustí původní akci a aktualizuje `state`.

Kombinovaný pracovní postup: Od kliknutí po zpětnou vazbu

Zde je popsáno, jak `useFormState` a `useFormStatus` spolupracují při vytváření úplné ověřovací smyčky:

1. Počáteční renderování: Formulář se renderuje s počátečním stavem poskytnutým funkcí `useFormState`. Nejsou zobrazeny žádné chyby.
2. Odeslání uživatelem: Uživatel klikne na tlačítko odeslání.
3. Čekající stav: Hook `useFormStatus` v tlačítku odeslání okamžitě hlásí `pending: true`. Tlačítko se deaktivuje a zobrazí se zpráva o načítání.
4. Provedení akce: Serverová akce (zabalena funkcí `useFormState`) je provedena s daty formuláře. Provádí ověřování.
5. Akce vrací: Akce selže při ověřování a vrátí objekt stavu, například: <br />`{ message: "Ověření selhalo", errors: { email: "Tento e-mail je již používán." } }`
6. Aktualizace stavu: `useFormState` obdrží tuto návratovou hodnotu a aktualizuje proměnnou `state`. To spustí opětovné renderování komponenty formuláře.
7. Zpětná vazba UI: Formulář se znovu renderuje. Stav `pending` z `useFormStatus` se změní na `false`. Komponenta nyní může číst `state.errors.email` a zobrazit chybovou zprávu vedle vstupního pole e-mailu.

Celý tento tok poskytuje uživateli jasnou, serverem autorizovanou zpětnou vazbu, řízenou výhradně stavem odeslání a výsledkem.

Praktická mistrovská třída: Vytvoření multifunkčního registračního formuláře

Pojďme si tyto koncepty upevnit vytvořením kompletního registračního formuláře v produkčním stylu. K ověřování použijeme serverovou akci a k vytvoření skvělé uživatelské zkušenosti použijeme `useFormState` i `useFormStatus`.

Krok 1: Definování serverové akce s ověřováním

Nejprve potřebujeme naši serverovou akci. Pro robustní ověřování použijeme populární knihovnu Zod. Tato akce bude umístěna v samostatném souboru, označeném direktivou `'use server';`, pokud používáte framework jako Next.js.

Soubor: actions/authActions.js

'use server'; import { z } from 'zod'; // Definujte schéma ověřování const registerSchema = z.object({ username: z.string().min(3, 'Uživatelské jméno musí mít alespoň 3 znaky.'), email: z.string().email('Zadejte platnou e-mailovou adresu.'), password: z.string().min(8, 'Heslo musí mít alespoň 8 znaků.'), }); // Definujte počáteční stav pro náš formulář export const initialState = { message: '', errors: {}, }; export async function registerUser(prevState, formData) { // 1. Ověřte data formuláře const validatedFields = registerSchema.safeParse( Object.fromEntries(formData.entries()) ); // 2. Pokud ověření selže, vraťte chyby if (!validatedFields.success) { return { message: 'Ověření selhalo. Zkontrolujte pole.', errors: validatedFields.error.flatten().fieldErrors, }; } // 3. (Simulace) Zkontrolujte, zda už uživatel existuje v databázi // Ve skutečné aplikaci byste zde provedli dotaz do databáze. if (validatedFields.data.email === 'user@example.com') { return { message: 'Registrace selhala.', errors: { email: ['Tento e-mail je již zaregistrován.'] }, }; } // 4. (Simulace) Vytvořte uživatele console.log('Vytvářím uživatele:', validatedFields.data); // 5. Vraťte stav úspěchu // Ve skutečné aplikaci byste se zde mohli přesměrovat pomocí `redirect()` z 'next/navigation' return { message: 'Uživatel byl úspěšně zaregistrován!', errors: {}, }; }

Tato serverová akce je mozkem našeho formuláře. Je soběstačná, bezpečná a poskytuje jasnou datovou strukturu pro stavy úspěchu i chyb.

Krok 2: Vytvoření opakovaně použitelných komponent, které si jsou vědomy stavu

Abychom udrželi naši hlavní komponentu formuláře čistou, vytvoříme vyhrazené komponenty pro naše vstupy a odesílací tlačítko.

Soubor: components/SubmitButton.js

'use client'; import { experimental_useFormStatus as useFormStatus } from 'react-dom'; export function SubmitButton({ label }) { const { pending } = useFormStatus(); return ( <button type="submit" disabled={pending} aria-disabled={pending} > {pending ? 'Zpracovávám...' : label} </button> ); }

Všimněte si použití `aria-disabled={pending}`. To je důležitá praxe přístupnosti, která zajišťuje, že čtečky obrazovky správně oznámí zakázaný stav.

Krok 3: Sestavení hlavního formuláře pomocí `useFormState`

Nyní pojďme vše spojit v naší hlavní komponentě formuláře. Použijeme `useFormState` k propojení našeho UI s akcí `registerUser`.

Soubor: components/RegistrationForm.js

'use client'; import { experimental_useFormState as useFormState } from 'react-dom'; import { registerUser, initialState } from '../actions/authActions'; import { SubmitButton } from './SubmitButton'; export function RegistrationForm() { const [state, formAction] = useFormState(registerUser, initialState); return ( <form action={formAction}> <h2>Registrovat se</h2> {state?.message && !state.errors && <p style={{ color: 'green' }}>{state.message}</p>} {state?.message && state.errors && <p style={{ color: 'red' }}>{state.message}</p>} <div> <label htmlFor="username">Uživatelské jméno</label> <input id="username" name="username" type="text" /> {state?.errors?.username && ( <p style={{ color: 'red' }} aria-live="polite"> {state.errors.username[0]} </p> )} </div> <div> <label htmlFor="email">E-mail</label> <input id="email" name="email" type="email" /> {state?.errors?.email && ( <p style={{ color: 'red' }} aria-live="polite"> {state.errors.email[0]} </p> )} </div> <div> <label htmlFor="password">Heslo</label> <input id="password" name="password" type="password" /> {state?.errors?.password && ( <p style={{ color: 'red' }} aria-live="polite"> {state.errors.password[0]} </p> )} </div> <SubmitButton label="Vytvořit účet" /> </form> ); }

Tato komponenta je nyní deklarativní a čistá. Nespravuje žádný stav sama, kromě objektu `state` poskytnutého funkcí `useFormState`. Jejím jediným úkolem je renderovat UI na základě tohoto stavu. Logika pro zakázání tlačítka je zapouzdřena v `SubmitButton` a veškerá logika ověřování je umístěna v `authActions.js`. Toto oddělení zájmů je velkým přínosem pro udržovatelnost.

Pokročilé techniky a profesionální osvědčené postupy

Zatímco základní vzor je výkonný, aplikace v reálném světě často vyžadují více nuancí. Pojďme prozkoumat některé pokročilé techniky.

Hybridní přístup: Kombinace okamžitého ověřování a ověřování po odeslání

Ověřování založené na stavu je vynikající pro kontroly na straně serveru, ale čekání na síťový roundtrip, aby se uživateli sdělilo, že jeho e-mail je neplatný, může být pomalé. Hybridní přístup je často nejlepší:

• Používejte ověřování HTML5: Nezapomeňte na základy! Atributy jako `required`, `type="email"`, `minLength` a `pattern` poskytují okamžitou, prohlížečem nativní zpětnou vazbu zdarma.
• Ověřování na straně klienta: Pro čistě kosmetické kontroly nebo kontroly formátování (např. indikátor síly hesla) můžete stále použít minimální množství handlerů `useState` a `onChange`.
• Autorita na straně serveru: Vyhraďte si serverovou akci pro nejkritičtější ověřování obchodní logiky, které nelze provést na klientovi (např. kontrola jedinečných uživatelských jmen, ověřování oproti záznamům v databázi).

To vám dává to nejlepší z obou světů: okamžitou zpětnou vazbu pro jednoduché chyby a autoritativní ověřování pro složitá pravidla.

Přístupnost (A11y): Vytváření formulářů pro každého

Přístupnost je nediskutovatelná. Při implementaci ověřování založeného na stavu mějte na paměti tyto body:

• Oznamujte chyby: V našem příkladu jsme použili `aria-live="polite"` na kontejnerech chybových zpráv. To říká čtečkám obrazovky, aby oznámily chybovou zprávu, jakmile se objeví, aniž by přerušily aktuální tok uživatele.
• Přiřaďte chyby ke vstupům: Pro robustnější připojení použijte atribut `aria-describedby`. Vstup může odkazovat na ID kontejneru chybových zpráv, čímž se vytvoří programové spojení.
• Správa fokusu: Po odeslání s chybami zvažte programové přesunutí fokusu na první neplatné pole. To ušetří uživatelům hledání toho, co se pokazilo.

Optimistické UI s vlastností `data` funkce `useFormStatus`

Představte si aplikaci sociálních médií, kde uživatel zveřejní komentář. Místo zobrazení indikátoru načítání po dobu jedné sekundy můžete aplikaci zrychlit. Vlastnost `data` z `useFormStatus` je pro to ideální.

Když je formulář odeslán, `pending` se změní na true a `data` je vyplněno `FormData` odeslání. Pomocí těchto `data` můžete okamžitě vykreslit nový komentář v dočasném, „čekajícím“ vizuálním stavu. Pokud serverová akce uspěje, nahradíte čekající komentář konečnými daty ze serveru. Pokud selže, můžete čekající komentář odebrat a zobrazit chybu. Díky tomu je aplikace neuvěřitelně responzivní.

Navigace v „experimentálních“ vodách

Je důležité se zabývat předponou „experimental“ v `experimental_useFormStatus` a `experimental_useFormState`.

Co „Experimentální“ ve skutečnosti znamená

Když React označí API jako experimentální, znamená to:

• API se může změnit: Název, argumenty nebo návratové hodnoty mohou být změněny v budoucí verzi Reactu, aniž by se řídily standardním sémantickým verzováním (SemVer) pro zásadní změny.
• Mohou se vyskytnout chyby: Jako nová funkce může mít okrajové případy, které dosud nejsou plně pochopeny nebo vyřešeny.
• Dokumentace může být řídká: Zatímco základní koncepty jsou zdokumentovány, podrobné průvodce pokročilými vzory se mohou stále vyvíjet.

Kdy přijmout a kdy čekat

Měli byste ji tedy použít ve svém projektu? Odpověď závisí na vašem kontextu:

• Dobré pro: Osobní projekty, interní nástroje, startupy nebo týmy, kterým vyhovuje správa potenciálních změn API. Použití v rámci frameworku, jako je Next.js (který tyto funkce integroval do svého App Routeru), je obecně bezpečnější sázka, protože framework může pomoci abstrahovat některé z churn.
• Používejte s opatrností pro: Rozsáhlé podnikové aplikace, systémy kritické pro chod podniku nebo projekty s dlouhodobými smlouvami o údržbě, kde je prvořadá stabilita API. V těchto případech může být rozumné počkat, dokud nebudou hooky povýšeny na stabilní API.

Vždy sledujte oficiální blog a dokumentaci Reactu, kde najdete oznámení týkající se stabilizace těchto hooků.

Závěr: Budoucnost formulářů v Reactu

Zavedení `experimental_useFormStatus` a souvisejících API je více než jen nový nástroj; představuje filozofický posun v tom, jak vytváříme interaktivní zážitky s Reactem. Přijetím základů webové platformy a společným umístěním stavové logiky na server můžeme vytvářet aplikace, které jsou jednodušší, odolnější a často výkonnější.

Viděli jsme, jak `useFormStatus` poskytuje čistý, oddělený způsob, jak mohou komponenty reagovat na životní cyklus odeslání formuláře. Eliminuje prop drilling pro čekající stavy a umožňuje elegantní, soběstačné komponenty UI, jako je chytré `SubmitButton`. V kombinaci s `useFormState` odemyká výkonný vzor ověřování založeného na stavu, kde je server konečnou autoritou a hlavní odpovědností klienta je renderovat stav vrácený serverovou akcí.

Zatímco značka „experimentální“ vyžaduje určitou míru opatrnosti, směr je jasný. Budoucnost formulářů v Reactu je budoucností postupného vylepšování, zjednodušené správy stavu a výkonné, bezproblémové integrace mezi logikou klienta a serveru. Osvojením si těchto nových hooků dnes se neučíte jen nové API; připravujete se na novou generaci vývoje webových aplikací s Reactem.